March 1, 1993      KeyAudit Docs

    KeyAudit

License Compliance and Software Audit Tool

KeyAudit™ produces an audit of software assets, and gives the network manager and end user a quick, convenient tool to bring a site into compliance with software license provisions.

Like SPAudit (the audit tool from the Software Publishers Association), KeyAudit scans mounted disks for all application programs and saves its audit reports in a file.  By structuring the file as tab delimited text, KeyAudit has the advantage of enabling easy analysis with any spreadsheet or database program.

Metered versus Dedicated Software

With the software industry’s increasing reliance on network licensing, one application file does not necessarily correspond to one software license.  Any software audit based exclusively on a file inventory will be insufficient to determine license compliance.  An audit must recognize and document programs that have a concurrent use license controlled by a license metering system.  The ability to distinguish a program file whose license is metered from a program file installed as a personal copy gives KeyAudit a critical advantage when auditing for license compliance.

When a site is using the KeyServer® license management package from Sassafras Software, “unkeyed” programs can be transformed into “keyed” copies with the push of a button.  KeyAudit also provides convenient tools for inspecting and removing any unlicensed programs and their auxiliary files.

What is KeyServer

KeyServer manages software license compliance throughout a Macintosh network.  An administrator can install license control into any Macintosh application and then centrally enforce the most common licenses including concurrent-use, zone restricted, and individual user licenses.

KeyServer has no detectable impact on users’ environments, and makes no assumptions about users’ hardware and software configurations.  A keyed application behaves identically to its unkeyed counterpart and can run from a remote file server or a local hard disk.  KeyServer is compatible with AppleShare, Novell, Pathworks, etc., but requires no file server and no dedicated hardware.

Network managers can remotely monitor current software usage, view transaction logs, and send bulletins to KeyServer users.  KeyServer gives users the convenience and performance of stand-alone applications while providing network administrators with central license management, usage reports, and access security.

KeyAudit At Sites With and Without KeyServer

Typically, a network manager or end user runs KeyAudit to inspect a disk.  Some program files are then transformed to keyed versions and others are deleted in order to maintain license compliance.  The completed audit report may be appended to a shared audit database for later analysis with any spreadsheet or database program.

At sites without a KeyServer to manage software licenses, KeyAudit can still perform its basic auditing function.  Disks can be scanned for programs and questionable files can be conveniently examined and deleted, but the option to bring program files under KeyServer license control will not be available.

In order to learn where software is installed throughout a site, a network manager might request that users append an audit of their disks to a central database.  A file server could be used to store the site-wide audit document so users can simply double click on the document to have their own information appended.  At a KeyServer managed site, an occasional scan of users’ disks would provide an opportunity to rein in or delete any uncontrolled program copies, while at the same time documenting license compliance efforts.

The collection and analysis of audit data alone may suffice to determine license compliance for some programs that are dedicated for single user access.  However, the flexible file sharing features of System 7 make license compliance efforts based only on audit data an ongoing challenge in all but the most static environments.  Controlling software access with KeyServer is proving to be a much more efficient and cost effective management option.

KeyAudit Features Summary

At any site
 • Produces a database of application files located on multiple disks
 • Automatically appends data from multiple audits to a central file 
 • Tab delimited text format enables analysis with database or spreadsheet
 • Button opens folder to inspect or delete questionable files 
 • Application recognition updated via Apple’s Compatibility Checker

At a KeyServer managed site (additional features)
 • Audit distinguishes KeyServer controlled from personal copies 
 • Conveniently transforms uncontrolled copies into KeyServer versions
 • Invites easy user participation in site-wide license compliance efforts
 • Helps managers and users to quickly bring site into license compliance

Using KeyAudit

KeyAudit was designed to be easy to use for infrequent or first-time audits, yet powerful enough to be useful for complex audits on very large computer networks.  When you first launch KeyAudit, press the return or enter key to immediately start an audit of your locally mounted disks.  Upon completion of the audit scan, KeyAudit displays all of the applications found.  If your Mac is connected to a KeyServer on your network, any uncontrolled copies of programs for which your KeyServer has a key will be selected in the audit window.  You can then simply click “Key Selected Programs” to instantly bring these programs under KeyServer’s control.

Program Categories

KeyAudit divides your programs into four categories, although all four categories might not be represented on your disks.  These four categories are described below:

Key Supported  You will only have programs in this category if you use the KeyServer.  Such a program is not under KeyServer’s control, but the particular KeyServer you use does know how to control the license for this program.  More than likely, other people on your network have copies of this program that are managed by your KeyServer.  A program in this category can be transformed into a keyed copy (managed by KeyServer) by selecting it and then clicking “Key Selected Programs”.  When the Key Supported checkbox is dimmed, it is an indication that either there is no KeyServer at your site or the network connection to your KeyServer has failed and should be checked for problems.

Keyed Program  Keyed Programs require permission from a KeyServer in order to run.  If you have a program in this category, you probably also have a KeyServer running on your network.

Not Keyed  If you do not have a KeyServer on your network, nearly all of your programs will fall into this category.  At a site with KeyServer, programs in this category are not managed by your KeyServer.  These might be programs that you personally own or that are licensed for your exclusive use, or they might be internally developed or site licensed.

Both the Key Supported and Not Keyed categories indicate a program copy that is not under KeyServer control.  Key Supported means your KeyServer has keyed some other copy of this program, so KeyAudit can transform this copy.  Not Keyed means that your KeyServer is not currently managing the license for the program in question.  Programs in this latter category cannot be transformed into keyed programs until the KeyServer administrator uses KeyConfigure to install control for that application on the KeyServer.

Special Program  By default, special programs include KeyAudit and other programs that change behavior when run at a KeyServer site.  If you got KeyAudit from your site administrator, KeyAudit might include other programs in this category.  Contact Sassafras Software to learn how KeyAudit can be customized to list other programs in the Special Program category.

Each program is placed in exactly one of the above categories.  If you have a KeyServer on your network, make sure that you are connected to it before running KeyAudit.   Check that you have KeyAccess in your System Folder, and that the KeyServer is selected in the Chooser.  When you are not connected to a KeyServer, the Key Supported checkbox is dimmed and programs that should appear in the Key Supported category appear in the Not Keyed category.

Quick Audit Option

When KeyAudit is run on a Mac that does not have KeyAccess (KeyServer’s client software) installed, it assumes that there is no KeyServer at the site.  At a site without a KeyServer, there is no possibility of transforming applications to KeyServer controlled versions so the “Key Supported” item will be dimmed.  It is also unlikely that any “Keyed Programs” will be discovered by KeyAudit’s careful inspection of program files, since without KeyServer, they can’t launch.  With only “Not Keyed” and “Special Program” as likely categories, there is little reason to open each application file for a careful inspection, so KeyAudit performs a Quick Audit by default.

On a Mac without KeyAccess, hold down the option key while clicking on the “Quick Audit” button to instruct KeyAudit to fully inspect all program files to see if any are keyed.  On a Mac that does have KeyAccess installed, KeyAudit’s “Audit” button will perform a full inspection of application files, even when there is no network connection to an active KeyServer.  You can override this default by holding down the option key while clicking on the “Audit” button.  KeyAudit will then perform a “Quick Audit”.

When you are not connected to a KeyServer, the Key Supported checkbox is dimmed and programs that should appear in the Key Supported category appear in the Not Keyed category.  If you do have a KeyServer on your network, make sure that you are connected to it before running KeyAudit.  Check that you have KeyAccess in your System Folder, and that the KeyServer is selected in the Chooser.  In order to actually transform programs into keyed versions, the KeyServer must have a key for KeyAudit.  See the section below, Adding Support for KeyAudit to an Existing KeyServer.

The Audit Window

KeyAudit’s main window contains the list of all applications found on your disk, and also gives quick access to KeyAudit’s features.  The upper part of the audit window is divided into three areas.  The Show/Save/Print area controls which programs are shown in the window, saved in an audit file, and printed when you choose Print from the file menu.  The Auditing area controls which volumes are included in subsequent audits, and includes the Audit button to initiate an audit.  The Actions area has two buttons which you can use to help bring your disk into compliance with software licenses.  These areas are pictured below:

If you do not have a KeyServer on your network, or if you do not have KeyAccess installed on your computer, The “Key Supported” and “Key Selected Programs” buttons are dimmed.

By default, KeyAudit sorts the programs in the audit list according to category.  You can change the order in which programs are displayed by clicking on the “Application”, “Volume”, or “Category” headings.  The effective sort order is always underlined.

Below the audit list KeyAudit displays the number of programs found in the audit, as well as the number of programs that are currently shown in the list.  To view all programs, check all of the available boxes in the Show/Save/Print area.  If you only wish to see programs from one category, check the corresponding box only, and turn the other check boxes off.

For System 7 users, there is a quick way to turn Balloon help on and off.  In the lower right corner of the audit window is the Balloon Help icon, with the words “Help Is On” or “Help Is Off” as appropriate.  Click this icon to toggle Balloon Help on and off.  KeyAudit supports Balloon Help for all of its menus and for the audit, information, and save options windows.

Performing an Audit

Before starting an audit, make sure that you have turned on the “Local Volumes” and “Remote Volumes” buttons as appropriate.  You may also want to insert or eject specific volumes before you begin the audit.  For example, you should Eject any CD-ROMs in order to avoid a lengthy audit of a disk whose contents will never change.

If the Local Volumes button is on (black diamond (âŒ¥) inside of the diamond frame), then the audit will include the disks connected to your computer.  If the Remote Volumes button is similarly turned on, the audit will include network volumes such as those mounted via AppleShare in the Chooser.  You must always have at least one of these buttons turned on, and may have both turned on at the same time as well.

Once you have selected which volumes to include in the audit, click the “Audit” button.  This initiates a new audit scan that replaces the previous audit.  Note that the settings of buttons in the “Show/Save/Print” are have no effect on the audit; they only affect which programs are displayed in the audit window and may be changed after the audit is complete.

Getting Program Information

KeyAudit knows more about a program than it displays in the main audit window.  There are a few different ways to get at this information.  First, to quickly determine where a program is on a disk, hold down the option key as you click on the program’s entry in the audit list.  This activates a pop-up menu of the folders in which the program is located, along with the official name of the program (if KeyAudit knows the official name).  The version of the program is also displayed in the pop-up menu (if it can be determined by KeyAudit).  If you are running System 7, choose one of the folders or the program name to display the item in the Finder.  Choose the program version in the menu to display the program’s Get Info window in the Finder.

Another way to get more information on a program is to double-click on it in the audit list.  The window pictured below appears, showing the program’s official name and publisher (if known), category, location on your disk, date of creation and last changes, and version.

This information window also contains two buttons to help you bring a disk into compliance with your software licenses.  The “View In Finder” button (which is only available if you are running System 7) is a quick way to locate a program on your disk.  When you click on this button, Finder comes to the foreground and displays the program.  This way you can easily locate the program’s support files.

The second button, “Key This Program”, is analogous to the main audit window’s “Key Selected Programs” utton, but it only keys the program displayed in the information window, and not the entire selection of programs.  This button is only available for programs in the “Key Supported” category.

If some of the information about a program is not available in the information window, this means KeyAudit’s internal database does not include information about the program.  One way to “teach” KeyAudit about more programs is described below, under Extending KeyAudit with Apple’s Compatibility Checker.

Saving an Audit

Once you have performed an audit on your disk, you might want to save a record of it in order to analyze the audit with a spreadsheet or database program.  You can either save the audit in a new file, or append the audit to an existing audit file (in order to combine multiple audits).

To save your audit, choose Save As from the File menu, then type a name for the audit and click Save in the Open File dialog box.  The Save Audit Options dialog appears, in which you can tailor the contents of the audit to your needs.  In the upper box, choose which categories you want to save in the audit file.  Below that are options for what information is saved for each program.

Audit files are text-only documents, with one program on each line and with columns separated by a tab character.  The columns contain the following information, and appear in the audit file only if you check the proper box in the Save Audit Options dialog:

Audit Date  The current date.  This date will be the same for all programs saved in your audit.  It is useful for when you save many audits in the same audit file.

Program Name  The official program name (if known by KeyAudit).  For example, if you have a program file named “Freehand” on your disk, the official name is actually “Aldus Freehand”.  This field is useful for determining where a particular program is on multiple disks, even when the program is named differently on each disk.

Volume Name  The disk on which the program is located.  This is useful for determining if the particular copy of the program is located on a local disk or a shared network disk.

Program Category  The audit category to which the program belongs.  This is always useful in saved audits so that you can determine if this copy of the program is managed by KeyServer, or if it is an unmanaged copy.

Path Name  The exact folder location of the program.  The entire list of enclosing folders appears in this field, starting with the name of the disk and ending with the name of the program as it appears on the disk.

Publisher Name  The name of the company that publishes the program.  This is useful when it comes time to contact a company about support or purchasing information.

Program Version  The version of the program on your disk.  This is useful for distinguishing between two different versions of the same program.  KeyAudit only shows version numbers for those program files that contain properly formatted version information.

User Name  The name of the user of the computer on which KeyAudit is running.  This is the same name entered in the Chooser (or in the Sharing Setup control panel under System 7).  The name is the same for all programs listed in the audit.  This field is useful for determining which user has a particular program, if the audit file contains audits for multiple users.

Custom  This field contains whatever information you type in the adjacent text box.  The text you type will appear in every entry of your audit.  If you are running System 7, the default value for this field is the Macintosh Name, as entered in the Sharing Setup control panel.

Once you have specified the information to be saved in the audit file, use the “Open With” pop-up menu to select the application with which you want to open the file.  The application you choose is opened when you double-click on the audit file, but the file contains text only, which means any word processor, spreadsheet, or database program can also open it.  When you save an audit as a KeyAudit document, you cannot use KeyAudit to overwrite the audit file, but you can still append new audit information to this file.  The choice you make here will be remembered for the next time you save an audit.

You can also append new audits onto existing audit files.  Choose one of the Append items from the File menu.  The Save Audit Options dialog box appears with the column boxes properly set up.  If you save your audit as a KeyAudit document, double-clicking on it in the Finder will open KeyAudit, and subsequent Append commands will save the audit to the end of the audit file.  For details, see the section Collecting a Site-Wide Audit with KeyAudit.

If some of the information about a program is not available in the saved audit, this means KeyAudit’s internal database does not include information about the program.  One way to “teach” KeyAudit about more programs is described below, under Extending KeyAudit with Apple’s Compatibility Checker.

Printing an Audit

To print an audit directly from within KeyAudit, first select which categories you wish to print, and then choose Print from the File menu.  KeyAudit will print only those programs that are shown in the audit window.  This is a simple way to get a hard copy of the list that appears in the audit window, but it is only the minimum of information.

To get a more complete printout, save the audit to a file and then use a database or spreadsheet program to format and print whatever information you require.

Extending KeyAudit with Apple’s Compatibility Checker

The information window for each program and saved audit files contain two important pieces of information for certain programs:  the official program name and the program publisher.  On its own, KeyAudit can only include this information for a limited number of popular applications.

In order to “teach” KeyAudit about other programs, you can obtain Apple’s Compatibility Checker 2.0 and place it in the same folder as KeyAudit.  When you launch KeyAudit, it searches for this program.  KeyAudit then uses the Compatibility Checker’s internal database of programs to find information about the programs in your audit.

When Apple comes out with a minor revision of the Compatibility Checker, replace your older copy with the new version and KeyAudit will automatically use the new information.

The Compatibility Checker is available from several sources.  It comes with any purchase of System 7.1, and can also be obtained on AppleLink (look in Software Sampler: Apple SW Updates: Macintosh: Utilities: Compatibility Checker 2.0) and via FTP on the Internet at ftp.apple.com (look in /dts/mac/sys.soft/compatibility-checker-2-0.hqx).

Before you download the Compatibility Checker, Apple requires that you read their general software license agreement, which can be found both on AppleLink (look in Software Sampler: Apple SW Updates: Apple Computer Inc. Software License Agreement) and on ftp.apple.com (look in /dts/help/software-license.txt).

Collecting a Site-Wide Audit with KeyAudit

An audit saved as a KeyAudit document a special property:  KeyAudit will not allow new audits to overwrite the existing file, audits can only be appended to the file.  To collect audit data for all of your networked Macs, place KeyAudit on a file server where all users at your site have read and write privileges.   Save an audit document on the file server in the same folder and optionally include Apple’s Compatibility Checker.  Be sure to select only the fields you are interested in and save theaudit file as a KeyAudit document (choose KeyAudit from the pop-up menu in the Save Audit Options dialog box).  Instruct your users to double click on this central audit document so that the results of their personal audit are automatically appended to it.

Tidbits: Anti-Virus & File Compression Software

The process of transforming an application to a keyed version may trigger  complaints from some anti-virus programs.  KeyAudit tests for virus checker compatibility when it first launches and, and posts a message warning of any possible conflicts.  In some cases, it may be necessary to turn off virus checking while KeyAudit is transforming programs into keyed versions.

Some file compression software changes application files into data files.  Depending on how the Mac operating system is patched by the compression software, such data files may or may not be recognized as application software, and thus compressed programs may not appear in an audit report.  Other file compression schemes wrap a decompressor application around a compressed file and may cause keyed software to appear as unkeyed, thus inviting the possibility of keying  an application twice.   You should test the behavior of KeyAudit carefully when using any compression program.  Call Sassafras Software for more detailed information on compression programs and how they may interact with KeyAudit and other software.

Adding Support for KeyAudit to an Existing KeyServer

While KeyAudit’s base level auditing functionality is available to everyone, one of the added benefits of using KeyAudit with KeyServer is KeyAudit’s ability to transform standard programs into KeyServer-managed programs.  For example, if you have previously installed control for MacWrite on your KeyServer, and KeyAudit locates an uncontrolled copy of MacWrite, you just select MacWrite and click the “Key Selected Programs” to instantly install KeyServer control into that copy of MacWrite.

To enable KeyAudit’s automatic keying feature, your KeyServer must have a special key for KeyAudit.  This enabling key can be obtained by writing to Sassafras Software on AppleLink, or by calling Sassafras (see below How to Contact Sassafras).  Note that this key is not a hardware device, nor is it a serial number.  It is a standard format KeyServer key, which lets you use all of KeyServer’s usual control mechanisms to manage access to the extended KeyAudit features.

How to Contact Sassafras

We welcome phone calls and e-mail.  Call us at (603) 643-3351.  Write to us on the Internet at Sassafras.dartmouth.edu, or on AppleLink at Sassafras.  Our postal address is Sassafras Software, P.O. Box 150 Hanover, NH 03755-0150 USA.

Sassafras maintains a bulletin board on AppleLink (in the Third Parties area) where users can exchange ideas on licensing and management issues.  Check the Sassafras bulletin board frequently for updates to KeyAudit, KeyServer, and associated utilities.  We encourage contributions of spreadsheet macros and database templates for analyzing KeyAudit data.

Copyright Notice and KeyAudit License
KeyAudit © 1993 Sassafras Software Inc.  All Rights Reserved.

End users are licensed to download and use without charge KeyAudit 3.1 from the Sassafras bulletin board on AppleLink.  KeyAudit 3.1 can be distributed freely among end users but commercial use or distribution, promotional use or distribution, bundling, and any form of mass distribution is expressly prohibited unless agreed to in advance through negotiation with Sassafras Software Inc.

If you have an appropriate use for KeyAudit in quantity, or you have a legitimate need for distributing KeyAudit, please contact Sassafras at the address given above.

 Sassafras, KeyServer, KeyAccess, and their associated product logos are registered trademarks of Sassafras Software Inc.

KeyAudit is a trademark of Sassafras Software Inc.

KeyServer, KeyAccess, and KeyAudit are copyrighted programs of Sassafras Software Inc.

Macintosh and AppleLink are registered trademarks of Apple Computer, Inc.  Finder is a trademark of Apple Computer, Inc.

All other product or brand names mentioned in this documentation are trademarks or registered trademarks of their respective companies.